\section{Introduction}

This chapter is an installation guide for {\em Chipper} and is intended to prepare your system for subsequent tutorials.  Chipper is a hardware
construction language embedded in the high-level programming language
Scala.

\subsection{Development Tool Installation}

If you are running Mac or a variant of Linux, you will need to install the appropriate tools for your OS, which are described in the following sections:

\subsubsection{MacOSX}

\begin{enumerate}
\item Install XCODE, including console tools.
\end{enumerate}

\subsubsection{Linux}

Install the following packages:

\begin{enumerate}
\item \verb|flo-llvm|
\item \verb+stanza+
\end{enumerate}

\noindent
using

\begin{bash}
sudo apt-get install
\end{bash}

% TODO: BOOTSTRAP CHIPPER COMPILER

\section{Setting Up the Tutorial}

In subsequent tutorials, you will be using the files distributed in the chipper-tutorial repository. To obtain these tutorials files, \verb+cd+ to the directory = \verb+$DIR+ where you want to place the Chipper tutorial and type:

\begin{bash}
cd $DIR
git clone https://github.com/ucb-bar/chipper-tutorial.git
\end{bash}

\noindent
Your copy of the Chipper Tutorial repository will then be in \verb+$DIR/chipper-tutorial+.  Define this as a variable in your bash environment named \verb+$TUT_DIR+.

This is the Chipper tutorial directory structure you should see, which is explained more in the next tutorial:

\begin{bash}
chipper-tutorial/  
  Makefile
  examples/
    Makefile
    Accumulator.stanza ...
  problems/
    Makefile
    Counter.stanza ...
  solutions/
    Makefile
    Counter.stanza ...
\end{bash}

\noindent 

The following tutorials will explain features of Chipper by presenting source code examples.  The repository is split into examples, problems, and solutions, where the problems have some piece of the design for you to fill out and where the examples and solutions are meant to be complete designs that should pass the given tests.  In order to run either, you simply need to change directory into the appropriate subdirectory and type \verb+make+ of the particular lesson name. We will use the repository to first test out if your machine is set up to use Chipper.

To test your Chipper distribution and verify that your system contains all the correct tools, run the following commands:

\begin{bash}
cd $TUT_DIR/examples
make Parity.out
\end{bash}

This will run a test build and will take a minute before it completes. If your system is set up correctly, you should see a messsage \verb+[success]+ followed by the total time of the run, and date and time of completion. If you see a success than your system has been set up correctly and you can continute to the next tutorial where we will explain more about the basics of Chipper.

\section{The Tutorials}

For these tutorials, we assume basic knowledge of digital circuits and blocks. 
Tutorial 1 will guide you through a quick compilation of the emulator and Verilog generation, and explain some basic constructs such as register and combinational logic.
Tutorial 2 will explain the basics of Chipper.
Tutorial 3 will explain how to use basic primitive types and logical operations that are used in Chipper and how to use them in context of several examples. 
Tutorial 4 will explain how to instantiate components and apply parametrization. 
Tutorial 5 will explain how to use the Chipper test harness. 
Tutorial 6 will explain how to set up your own Chipper project and how to build it.
Tutorial 7 will revisit conditional register updates and explain how to construct memories.
Finally, tutorial 8 will introduce how to use Stanza constructs such as \verb+if...else+ and \verb+for+ loops.

Along the way there are assignments highlighted with \red{red} titles.  
These assignments are built around files in the tutorial problems directory.
In order to check successful completion of the entire set of getting started assignments run:
\begin{bash}
cd $TUT_DIR/problems
make getting-started
\end{bash}

\noindent
until no error appears.

The following set of tutorials were written using the build settings Stanza version 385 and Chipper version 0.1.
